R Markdown is a tool built into R and Rstudio that allows users to create documents/dashboards/reports with embedded r code and outputs directly in the RStudio IDE. To begin using Rmarkdown you will need to install the"rmarkdown" package.
Rmarkdown is incredibly useful for creating reports for analyses, or for communicating with colleagues in situations where you wish to combine text and statistical outputs or maps in a single document, and without the need for copying or pasting onto other software platforms. It is also useful for situations where you want to share both the code and the output as it would appear in Rstudio.
R Markdown was designed for easier reproducibility, since both code and narratives are in the same document, with outputs derived from the source code. This R Markdown document will be covering the basic steps for creating an R Markdown document, with short demonstrations on some of its most useful/common functionalities. Much of the material here can be found online and in much greater detail here at R Markdown: The Definitive Guide with helpful shortcuts for the Markdown syntax found on this cheatsheet. Another good resources is Pimp my Rmarkdown, a blog covering different topics on how to improve your reports.
For creating dashboards in rmarkdown I would recommend flexdashboards and for creating remark.js presentations I would also recommend the xaringan package.
Tables or dataframes can be displayed in their tabular form by either printing a dataframe that is in the R environmnet, or by using one of several packages for creating customizable tables like the kable() function in the knitr package or the DT package for accessing the data.tables library
library(knitr)
kable(head(mtcars))
| mpg | cyl | disp | hp | drat | wt | qsec | vs | am | gear | carb | |
|---|---|---|---|---|---|---|---|---|---|---|---|
| Mazda RX4 | 21.0 | 6 | 160 | 110 | 3.90 | 2.620 | 16.46 | 0 | 1 | 4 | 4 |
| Mazda RX4 Wag | 21.0 | 6 | 160 | 110 | 3.90 | 2.875 | 17.02 | 0 | 1 | 4 | 4 |
| Datsun 710 | 22.8 | 4 | 108 | 93 | 3.85 | 2.320 | 18.61 | 1 | 1 | 4 | 1 |
| Hornet 4 Drive | 21.4 | 6 | 258 | 110 | 3.08 | 3.215 | 19.44 | 1 | 0 | 3 | 1 |
| Hornet Sportabout | 18.7 | 8 | 360 | 175 | 3.15 | 3.440 | 17.02 | 0 | 0 | 3 | 2 |
| Valiant | 18.1 | 6 | 225 | 105 | 2.76 | 3.460 | 20.22 | 1 | 0 | 3 | 1 |
Any graphical outputs from evaluated code chunks will appear in-line as they appear in the document. When outputting to an HTML document it is possible to include interactive plots like those available from the plotly package.
library(tidyverse)
library(plotly)
p <- ggplot(mtcars, aes(x = hp, y = mpg)) +
geom_point(aes(color = factor(cyl))) +
geom_smooth(aes(color = factor(cyl)),
method = "lm", se = FALSE)
ggplotly(p)
In line formulas are written between single dollar \((\$)\) signs. Done this way the “von Bert” formula \(l_t = L_{\infty}(1-e^{-K(t-t_0)})\) will appear beside normal text. The formula notation in R Markdown follows LaTeX notation which makes adding special symbols as simple as looking them up here
Formulas can also be displayed out of text by bracketing with double dollar \((\$\$)\) signs : \[l_t = L_\infty(1-e^{-K(t-t_0)}) \]
You can also use math environments inside these closures to allow for matrix notation e.g., \[\begin{array}{ccc} x_{11} & x_{12} & x_{13}\\ x_{21} & x_{22} & x_{23} \end{array}\]
If the selected output type for your rmarkdown document is HTML (the default option), it will be possible to include interactive displays like zoomable maps/plots and searchable tables in your document.
library(leaflet)
m <- leaflet() %>%
addTiles() %>% # Add default OpenStreetMap map tiles
setView(-88.943634, 30.441863, zoom = 16) %>%
addMarkers(lng = -88.943634, lat = 30.441863,
popup="Oh look, Its us!")
m
Assuming that both R and Rstudio have been installed, users only need to install the “Rmarkdown” package from CRAN to begin creating html/word documents. In order to create pdf documents directly from Rstudio using R Markdown, users will need to install a distribution of LaTeX.
A full installation of LaTeX is rather large, and the authors of R Markdown and myself would strongly suggest installing tinytex as an alternative.
# Install from CRAN
install.packages('rmarkdown')
install.packages("tinytex")
tinytex::install_tinytex() # install TinyTeX
Files can be created in RStudio by navigating to the
file tab –> New file –> R Markdown
You will then be prompted to add a title and name an author before finally selecting an output type.
Most R Markdown documents are composed of three parts:
The beginning of each markdown document will contain several lines of pre-formatted text upon creation. For example :
---
title: "Rmarkdown Guide"
author: "Adam A. Kemberling"
date: "12/17/2018"
output:
html_document:
toc: true
toc_float: true
---
This chunk of text formats the output of the document and is where you would make changes to add/remove features like a table of contents or change from an html document to a word or pdf document.
Indentation is important in this section of the document, so be sure when you are trying to match code online that you pay attention to the details.
---
title: "Multiple Columns"
output: flexdashboard::flex_dashboard
---
Column {data-width=600}
-------------------------------------
### Chart 1
## R code for Chart 1
#```{r}
#
#```
Column {data-width=400}
-------------------------------------
### Chart 2
## R code for Chart 2
#```{r}
#
#```
### Chart 3
## R code for Chart 3
#```{r}
#
#```
YAML metadata can be fully customized using css or html notation, however it is usually much easier to find a theme that you like and use their pre-packaged styles.
Plain text entered into the document will appear (for the most part) as is text in the document. Text entered outside of codeblocks can be changed using Pandoc’s Markdown syntax. This is what allows you to create things like headers, lists, and italic or bold font changes.
Examples of how the markdown syntax works:
**text***text*A full set of syntax options can be found here
R Code blocks are created by typing: “```{r}”, and they are closed by typing three more backticks like the ones at the start of the code block. R Markdown supports the use of other programming language evaluation, so it is important to designate what language is being used within the curly brackets at the start of the codeblock.
There are also a number of options that can be included within that enclosure that will change how the output of code is displayed
This is also where you would set figure width options for any plots in your code block.
In the event that you are making a template, and wish to set keywords or macrovariables that will populate themselves in the text, you will set them as you normally do within code blocks using keyword <- "whatever you want to paste then to have code evaluated within text you use a single backtick " ` " followed by “r” and close the inline codeblock with another backtick. This is also useful when you want to pull model results directly into the text using the coefficients function coef(),
ex. coef(mymodel)[1]
The way R and R markdown convert the three elements of a markdown document into a single document/report is done in two steps:
These two steps are performed automatically and behind the scenes by clicking the knit button at the top of your .Rmd file in Rstudio, it is the icon that resembles a ball of yarn. Once knit your new file will appear in the current working directory.
CSS or html can be added directly into your rmarkdown using code chunks and the HTML() function in the htmltools package.
The code chunk below is html code used to change the style of div containers of the class “.header_1_class” by changing the background color to light blue, the border radius to 5 pixels, and the padding to 20 pixels. It also changes the background color of containers with the ID of “#header_1_id”. The class is “.header_1_class” because I named it that, you can name the class whatever you want, but it is easier to keep track of the classes if their names are meaningful. The css has to reference an object in your html document to do anything.
Alternatively you can put the exact same code in your stylesheet, and then just label your sections correctly in the rmarkdown file to have the same effect. It may be preferable to enter any “code” within a code chunk for the visual distinction when writing your .Rmnd files.
htmltools::HTML(
'
<style>
/* Set A Style for a Specific Class */
.header_1_class { background-color:#e6f0ff;
border-radius: 5px;
padding: 20px;}
/* Set A Style for a Specific ID */
#header_1_id { background-color: #ACACAC;}
</style>
'
)
The below sections will have style applied to them because the headers have been given ID and class labels “#header_1_id” & “.header_1_class”, which I set with # Identifying sections by their ID {#header_1_id} & # Identifying Sections by their class {.header_1_class}
This section is identified in the above code chunk by its ID
This section should is identifiable in the above css statement by its class
You could also out the style details in a stylesheet, and identify these sections the same way.
If you are already familiar with html you can add whatever html you want directly using this method. This is great if you just want to copy another pages layout or parts of it.
For example, you could add a table (or any other element you find on a web page) the hard way if you wanted to by adding the html code directly:
htmltools::HTML(
'
<table style="width:100%">
<tr>
<th>Firstname</th>
<th>Lastname</th>
<th>Age</th>
</tr>
<tr>
<td>Jill</td>
<td>Smith</td>
<td>50</td>
</tr>
<tr>
<td>Eve</td>
<td>Jackson</td>
<td>94</td>
</tr>
</table>
<br/>
'
)
| Firstname | Lastname | Age |
|---|---|---|
| Jill | Smith | 50 |
| Eve | Jackson | 94 |
But keep in mind that the purpose of rmarkdown is to get you there without learning html, and there is almost always a way to do that in R language.
More (pretty much anything you could want to know) about html and css can be found for free at w3schools.com
HTML can also be added directly into the body of the document, as well.
| Firstname | Lastname | Age |
|---|---|---|
| Jill | Smith | 50 |
| Eve | Jackson | 94 |